package com.sky.service;

import com.sky.dto.PageQueryDTO;
import com.sky.entity.AdminRoles;
import com.sky.entity.AdminPermissions;
import com.sky.vo.AdminRoleVO;
import cn.mybatis.mp.core.mybatis.mapper.context.Pager;
import com.sky.exception.BaseException;

import java.util.List;

/**
 * 管理员角色服务接口
 * 提供管理员角色管理的相关功能，包括：
 * 1. 角色的基本CRUD操作
 * 2. 角色权限的分配和管理
 * 3. 管理员与角色的关联管理
 * 4. 角色查询和验证功能
 */
public interface AdminRoleService {

    /**
     * 获取所有角色列表
     * 查询系统中所有已定义的角色信息
     *
     * @return 角色列表，包含所有角色的详细信息
     */
    List<AdminRoles> getAllRoles();

    /**
     * 获取所有权限列表
     * 查询系统中所有已定义的权限信息
     *
     * @return 权限列表，包含所有权限的详细信息
     */
    List<AdminPermissions> getAllPermissions();

    /**
     * 创建新角色
     * 1. 检查角色名是否已存在
     * 2. 创建新的角色记录
     * 3. 建立角色与权限的关联关系
     *
     * @param role 角色信息，包含角色名称、描述等基本信息
     * @param permissionIds 要分配给该角色的权限ID列表
     * @throws BaseException 当角色名已存在时抛出异常
     */
    void createRole(AdminRoles role, List<Integer> permissionIds);

    /**
     * 更新角色信息
     * 1. 验证角色是否存在
     * 2. 如果修改了角色名，检查新名称是否与其他角色冲突
     * 3. 更新角色基本信息
     * 4. 更新角色的权限关联
     *
     * @param role 更新后的角色信息
     * @param permissionIds 更新后的权限ID列表
     * @throws BaseException 当角色不存在或新角色名已存在时抛出异常
     */
    void updateRole(AdminRoles role, List<Integer> permissionIds);

    /**
     * 删除角色
     * 1. 检查角色是否存在
     * 2. 检查是否有管理员正在使用该角色
     * 3. 删除角色信息
     * 4. 删除角色的权限关联
     *
     * @param roleId 要删除的角色ID
     * @throws BaseException 当角色不存在或正在使用中时抛出异常
     */
    void deleteRole(Integer roleId);

    /**
     * 获取角色的所有权限ID
     * 查询指定角色被分配的所有权限标识
     *
     * @param roleId 角色ID
     * @return 该角色拥有的所有权限ID列表
     */
    List<Integer> getRolePermissions(Integer roleId);

    /**
     * 移除管理员的角色
     * 删除管理员与指定角色的关联关系
     *
     * @param adminId 管理员ID
     * @param roleIds 要移除的角色ID列表
     */
    void removeRolesFromAdmin(Integer adminId, List<Integer> roleIds);

    /**
     * 分页查询角色列表
     * 1. 支持按角色名称模糊搜索
     * 2. 返回分页结果，包含角色的详细信息（包括权限列表）
     *
     * @param pager 分页参数，包含页码、每页大小等信息
     * @param name 角色名称（可选，用于搜索）
     * @return 分页结果，包含角色列表和分页信息
     */
    Pager<AdminRoleVO> pageQuery(PageQueryDTO pager, String name);

    /**
     * 检查角色是否存在
     * 根据角色ID查询角色是否在系统中存在
     *
     * @param roleId 角色ID
     * @return true-角色存在，false-角色不存在
     */
    boolean roleExists(Integer roleId);

    /**
     * 获取使用某个角色的管理员数量
     * 统计使用指定角色的管理员总数，用于角色删除前的检查
     *
     * @param roleId 角色ID
     * @return 使用该角色的管理员数量
     */
    long getAdminCountByRole(Integer roleId);
} 